home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / flist24.zip / FLIST.DOC < prev    next >
Text File  |  1993-01-10  |  12KB  |  251 lines
  1.  
  2. FLIST -- Generates file lists based on privilege levels and keys
  3.  
  4. Version 2.4   (1/10/93)
  5.  
  6. Written by Bob Quinlan of Austin, Texas, USA
  7. Sysop of Red October at 512-834-2593 (1:382/111)
  8. Special thanks to David Powers for suggestions and code.
  9.  
  10. Copyright 1993 by Bob Quinlan
  11.  
  12. Compatible with Maximus 2.00 and 2.01
  13.  
  14.  
  15. This program generates a list of files that a user with a particular
  16. privilege level and set of keys could access.  It is intended to make
  17. the procedure independent of changes to the structure of your file
  18. areas.  Instead of specifying which areas should be included you just
  19. specify what sort of user you want the list to apply to.
  20.  
  21. You can also create lists of new files.  Just use /D to specify how many
  22. days of files you want to list.
  23.  
  24.     /Afile      Area file.  You can use this to specify a path to
  25.                 AREA.DAT or to refer to another file (although it must
  26.                 follow the AREA.DAT format).  The filename must be
  27.                 included along with the path.  Defaults to AREA.DAT in
  28.                 the current directory.
  29.  
  30.     /B          Include barricaded areas.  If this switch is not
  31.                 included no barricaded areas will be included.
  32.  
  33.     /C          Include comments from the FILES.BBS file lists.  By
  34.                 default only files and their descriptions are included.
  35.  
  36.                 Using this switch has one side-effect!  Normally area
  37.                 headers are only generated for areas that have files in
  38.                 them.  /C will cause them to be generated for any area
  39.                 that has comments as well.  Do not use /C if you only
  40.                 want areas that have files in them to appear!  (I
  41.                 recommend not using /C with /D so that you don't show
  42.                 lots of apparently empty file areas.)
  43.  
  44.     /Ddays      Days.  Excludes all files more than this many days old.
  45.                 Use this switch to create lists of new files.
  46.  
  47.     /Ffile      Output file.  The pathname of the file you want the file
  48.                 list written to.  Defaults to FLIST.TXT in the current
  49.                 area.
  50.  
  51.     /HAfile     Area header file.  The contents of this file will be
  52.                 added to the report for each area header.  There are
  53.                 several sequences you can embed in the file that have
  54.                 special meanings.  All of the codes explained under /HS
  55.                 are allowed except for %C and %B.
  56.  
  57.                 If no area header file is specified a default header
  58.                 will be used.
  59.  
  60.     /HBfile     Beginning header file.  The contents of this file will
  61.                 be added to the beginning of the report.  There are
  62.                 several sequences you can embed in the file that have
  63.                 special meanings.  The codes %D, %T, and %A (explained
  64.                 under /HS) are allowed.
  65.  
  66.     /HEfile     End header file.  The contents of this file will be
  67.                 added to the end of the report.  There are several
  68.                 sequences you can embed in the file that have special
  69.                 meanings.  The codes %F, %S, %D, %T, and %A (explained
  70.                 under /HS) are allowed.
  71.  
  72.     /HSfile     Area summary header file.  The contents of this file
  73.                 will be added to the report after each area.  There are
  74.                 several sequences you can embed in the file that have
  75.                 special meanings:
  76.  
  77.                     %N will be replaced with the area name.
  78.                     %I will be replaced with the area information.
  79.                     %C will be replaced with the area file count.
  80.                     %B will be replaced with the area file size total (bytes).
  81.                     %F will be replaced with the overall file count.
  82.                     %S will be replaced with the overall file size total.
  83.                     %D will be replaced with the report date.
  84.                     %T will be replaced with the report time.
  85.                     %A will be replaced with the age of the files
  86.                        included in the report.  Do not use this except
  87.                        with the /D command line parameter!
  88.  
  89.                     Any of these may be followed by an L, R, or C
  90.                     immediately followed by a number.  These will left,
  91.                     right, or center justify the value in a field of the
  92.                     specified width.
  93.  
  94.                     You can also follow any of the above with an NF or
  95.                     with an Fx.  NF stands for "no fill" and has no
  96.                     effect (see examples).  Fx stands for "fill" and
  97.                     will cause the entire field to be replaced by an
  98.                     equivalent number of the character 'x'.  This is
  99.                     useful when drawing boxes.
  100.  
  101.     /Kkeys      Keys to use for access to locked areas.  Keys are
  102.                 represented by 1-8 and A-X.  An asterisk (*) turns on
  103.                 all of the keys.  Multiple keys can be specified in one
  104.                 /K argument (such as /K12B).
  105.  
  106.     /N          No-wrap.  Leave long description lines intact.  The
  107.                 default is to wrap them.
  108.  
  109.     /O          Include offline files.  By default files that are listed
  110.                 but not present are not included in the list.
  111.  
  112.     /Ppriv      Privilege to use for access to areas.  Only the first
  113.                 letter of the level name is required.  Legal values are:
  114.                     Twit
  115.                     Disgrace
  116.                     Limited
  117.                     Normal
  118.                     Worthy
  119.                     Privil
  120.                     Favored
  121.                     Extra
  122.                     Clerk
  123.                     AsstSysop
  124.                     Sysop
  125.                     Hidden
  126.                 Defaults to Normal.
  127.  
  128.     /T          Truncate long description lines.  The default is to wrap
  129.                 them.
  130.  
  131.     /Vcount     Volume.  'count' is the number of files each dot stands
  132.                 for in the progress indicator.  Zero will turn off all
  133.                 progress displays.
  134.  
  135.     /Wcolumn    Wrap column.  Sets line wrapping to the specified column
  136.                 relative to the left margin.
  137.  
  138. Let me show you an example of how to use the %N and %I parameters in an
  139. area header file (defined with the /HA switch).  The purpose of those
  140. parameters is to let you build boxes that will conform to the size of
  141. the text produced by %N and %I.  Here is an example of a simple header
  142. box using these parameters:
  143.  
  144. ┌──%NF───┬──%IF───┐
  145. │  %NNF  │  %INF  │
  146. └──%NF───┴──%IF───┘
  147.  
  148. Note that the characters following the %NF and %IF look like a part of
  149. the regular text, but are actually the characters that will be used to
  150. fill out the parameters to the desired length.
  151.  
  152. This will expand to something that looks like this:
  153.  
  154. ┌───────┬───────────────────────────────────────────┐
  155. │  MAX  │  Maximus BBS files and related utilities  │
  156. └───────┴───────────────────────────────────────────┘
  157.  
  158. Now you can see why the apparently useless NF modifier can be useful. It
  159. pads out the shorter embedded codes so that they visually match those in
  160. the surrounding lines.  The following would produce exactly the same
  161. result as the previous example, but it is a lot harder to figure out how
  162. everything will match up:
  163.  
  164. ┌──%NF───┬──%IF───┐
  165. │  %N  │  %I  │
  166. └──%NF───┴──%IF───┘
  167.  
  168. Here is an example using fixed width fields.  This also right justifies
  169. the area name and left justifies the area information:
  170.  
  171. ┌─%NR9F──┬─%IL50F──┐
  172. │ %NR9NF │ %IL50NF │
  173. └─%NR9F──┴─%IL50F──┘
  174.  
  175. Which will expand to something that looks like this:
  176.  
  177. ┌───────────┬────────────────────────────────────────────────────┐
  178. │       MAX │ Maximus BBS files and related utilities            │
  179. └───────────┴────────────────────────────────────────────────────┘
  180.  
  181.  
  182. FLIST returns the following ERRORLEVELS:
  183.     0 = success
  184.     1 = bad command line parameter
  185.     2 = unable to open AREA.DAT
  186.     3 = unable to open header file
  187.     4 = unable to open output file
  188.     5 = not enough memory to run
  189.     6 = string overflow processing header
  190.  
  191. NOTICE:  You may use, copy, and distribute this program freely as long
  192. as you insure that both the executable and the documentation (.DOC)
  193. files are included in the distribution package.  The source code does
  194. not need to be included.  You may modify this program and document, so
  195. long as reasonable credit is given to the original author if a
  196. substantial portion of the original remains intact.  The author is not
  197. responsible for any losses which may occur either directly or indirectly
  198. as a result of using this program.
  199.  
  200. This program uses the Maximus structures written by Scott J. Dudley.
  201.  
  202. HISTORY:
  203. Version 2.4   (1/10/93) -- Added the /HS option to allow customized area
  204.                            summary headers in the report.  Added new
  205.                            embedded variables for total and area file
  206.                            counts and file sizes.  Fixed a bug that
  207.                            occurred when inappropriate replacement codes
  208.                            were used in a header.
  209. Version 2.3   (1/10/93) -- Added /W parameter to allow line-wrapping to
  210.                            different lengths.  List "offline" as the
  211.                            size for offline file entries.
  212. Version 2.2  (11/04/92) -- Fixed minor date offsets caused by default
  213.                            timezone and daylight savings adjustments.
  214.                            Added the /V switch to limit screen output.
  215.                            /V0 replaces the /Q switch.
  216. Version 2.1   (8/26/92) -- Added the /Q switch to eliminate the progress
  217.                            display.  Now returns different errorlevels
  218.                            for each possible error.  Fixed problem with
  219.                            headers before comments.
  220. Version 2.0   (8/23/92) -- Added more error checking.
  221. Version 1.9   (8/22/92) -- Added a progress display.  Fixed a memory
  222.                            corruption bug.
  223. Version 1.8   (8/20/92) -- Added fixed width fields with left, right,
  224.                            and centered justification for embedded
  225.                            variables.  Changed the previous codes for
  226.                            embedded variables!  Removed built-in help to
  227.                            reduce memory requirements.
  228. Version 1.7   (8/10/92) -- Added embedded variables to the begin and end
  229.                            headers.  Note: This eliminated the automatic
  230.                            file age comment that used to be included for
  231.                            newfile lists.
  232. Version 1.6   (8/10/92) -- Added the /HA option to allow customized area
  233.                            headers in the report.  This is an expansion
  234.                            of an idea and code by David Powers.
  235. Version 1.5   (8/09/92) -- Added the /HB and /HE options to allow
  236.                            customized beginning and end text in the
  237.                            report.  Added /? help option to print the
  238.                            parameter list.  Added a clearer explanation
  239.                            of /C's effect on area headers.
  240. Version 1.4   (8/07/92) -- Added the /C option to include file list
  241.                            comments.  Added code to recognize free
  242.                            switches so they do not show up in the
  243.                            descriptions.  Fixed error if first entry in
  244.                            AREA.DAT did not include a file area.
  245. Version 1.3   (8/06/92) -- Read the file list filename from AREA.DAT
  246.                            instead of assuming FILES.BBS.
  247. Version 1.2   (8/02/92) -- Added days header for new files list.
  248. Version 1.1   (7/30/92) -- Added file age cutoff.
  249. Version 1.0   (6/30/92) -- Original release.  Written in Borland C.
  250.  
  251.